//+------------------------------------------------------------------+
//|                                                         IMap.mqh |
//|                             Copyright 2000-2025, MetaQuotes Ltd. |
//|                                             https://www.mql5.com |
//+------------------------------------------------------------------+
#include "ICollection.h"  // 引入基础集合接口，继承集合管理的核心能力

// 前向声明键值对类（用于接口定义，具体实现需单独定义）
template<typename TKey, typename TValue>
class CKeyValuePair;

//+------------------------------------------------------------------+
//| IMap<TKey, TValue> 泛型接口：键值对映射的标准化接口               |
//| 核心定位：继承自 ICollection 接口，专注于键值对（Key-Value）数据的管理， |
//|           提供通过唯一键快速访问值的能力，是哈希表、字典等结构的抽象契约 |
//| 泛型设计：双参数 <TKey, TValue> 分别指定键和值的类型，支持任意组合（如订单ID→订单信息、|
//|           品种代码→价格），兼顾类型安全与灵活性                     |
//| 核心价值：解决“通过唯一标识快速定位数据”的问题，相比数组遍历（O(n)），映射结构的 |
//|           查找效率可达 O(1)（哈希实现），大幅提升EA中高频数据访问场景的性能 |
//| 与父接口的关系：继承 ICollection 对集合的基础管理能力（如Count()、Clear()），|
//|               扩展键值对特有的操作（如按键增删改查），形成完整的映射能力 |
//+------------------------------------------------------------------+
template<typename TKey, typename TValue>
interface IMap : public ICollection<CKeyValuePair<TKey, TValue>*>
  {
   //----------------------------------------------------------------
   // 键值对添加：向映射中插入新的键值关系（键必须唯一）
   //----------------------------------------------------------------
   /**
    * @brief 添加键值对（键不存在时成功，存在时失败）
    * @param key [in] 唯一标识键（如订单ID、品种代码）
    * @param value [in] 与键关联的值（如订单详情、价格）
    * @return bool - 操作结果：true=添加成功；false=键已存在或无效
    * @note 键的唯一性是核心约束，确保通过键能唯一确定一个值
    *       示例：添加订单映射 → Add(12345, orderInfo)
    */
   bool      Add(TKey key, TValue value);

   //----------------------------------------------------------------
   // 包含性检查：验证映射中是否存在指定的键值组合
   //----------------------------------------------------------------
   /**
    * @brief 检查是否存在特定的键值对
    * @param key [in] 待检查的键
    * @param value [in] 待检查的值
    * @return bool - 检查结果：true=存在该键且对应值匹配；false=键不存在或值不匹配
    * @note 用于精确验证键值关系（如确认"EURUSD"的价格是否为1.0900）
    */
   bool      Contains(TKey key, TValue value);

   //----------------------------------------------------------------
   // 按键删除：移除指定键对应的键值对
   //----------------------------------------------------------------
   /**
    * @brief 移除键对应的键值对
    * @param key [in] 待删除的键
    * @return bool - 操作结果：true=删除成功（键存在）；false=删除失败（键不存在）
    * @note 删除后，该键的所有关联数据将被清除
    *       示例：移除已平仓订单 → Remove(12345)
    */
   bool      Remove(TKey key);

   //----------------------------------------------------------------
   // 按键取值：安全获取指定键对应的值
   //----------------------------------------------------------------
   /**
    * @brief 通过键获取对应的值（键不存在时返回失败）
    * @param key [in] 用于查找的键
    * @param value [out] 输出参数，接收找到的值
    * @return bool - 操作结果：true=获取成功；false=键不存在
    * @note 核心高效操作，无需遍历即可定位值（哈希实现耗时可忽略）
    *       示例：查询订单详情 → TryGetValue(12345, orderInfo)
    */
   bool      TryGetValue(TKey key, TValue &value);

   //----------------------------------------------------------------
   // 按键设值：更新指定键对应的值
   //----------------------------------------------------------------
   /**
    * @brief 修改已有键对应的值（键不存在时返回失败）
    * @param key [in] 用于定位的键
    * @param value [in] 新值
    * @return bool - 操作结果：true=更新成功；false=键不存在
    * @note 用于动态更新数据（如刷新品种最新价格）
    *       示例：更新价格 → TrySetValue("EURUSD", 1.0905)
    */
   bool      TrySetValue(TKey key, TValue value);

   //----------------------------------------------------------------
   // 键值分离复制：将所有键和值分别复制到数组
   //----------------------------------------------------------------
   /**
    * @brief 批量复制键和值到两个数组（保持位置对应关系）
    * @param dst_keys [out] 存储键的目标数组
    * @param dst_values [out] 存储值的目标数组
    * @param dst_start [in] 数组起始复制索引（默认从0开始）
    * @return int - 实际复制的键值对数量（受数组容量限制）
    * @note 用于批量处理场景（如遍历所有品种或订单）
    */
   int       CopyTo(TKey &dst_keys[], TValue &dst_values[], const int dst_start=0);
  };
//+------------------------------------------------------------------+